MBasic: Learning about the BasicATOM
Chapter 1 - Introduction What is a BasicATOM module? The BasicATOM module(Standard and Pro) is a self contained microcontroller; essentially a microcomputer with memory and support circuitry in a single plug-in package. The BasicATOM’s command language is programmed using a convenient Basic-like compiler which runs on a PC. This special version of Basic, called MBasic, is very powerful and easy to use. MBasic comes bundled with an Integrated Development Environment (IDE) offering programming and debugging tools. This Manual This manual is designed for both first time and experienced microcontroller users. It describes setup and programming of the BasicATOM module. Hardware details and schematics are provided separately in the form of data sheets. Models covered by this manual are BasicATOM 24-M,28-M,40-M,Pro24-M, Pro28-M and Pro40-M. For more information about a particular device refer to its Data Sheet. Printed data sheets are included with each product, and all data sheets are available from the download section of the Basic Micro web site at http://www.basicmicro.com. Note:' Data sheets for other products mentioned in this manual are available from the manufacturers, and can usually be found easily online using a search engine such as Google. On-line Discussion Forums Current Lynxmotion, a primary supporter of the BasicATOM maintains a discussion forum at http://www.lynxmotion.net. The discussion forums are free and will help you to find information and assistance quickly. Information Resources In addition to other resources mentioned in this manual, you can also find useful information by using the search feature of the online discussion forums at the Lynxmotion web site. Updates Atom Pro software updates will be available to new and current customers. We recommend joining the discussion forums at http://www.basicmicro.com where update announcements will be posted. Technical Support Technical support is available by phone, 800-535-9161, and by email, support@basicmicro.com. In order to assure a proper response. Please include a copy of the program you are having problems with, the hardware you are using, BasicATOM vision, and any prototyping board used. By including this information with your email, you can help us to answer your questions quickly. Chapter 2 - The BasicATOM Overview The BasicATOM is a complete microcontroller with a wide range of programmable functions. User-programming is done with MBasic, a Basic like compiler, developed by Basic Micro, running on a PC, and the resulting object code is downloaded to the BasicATOM module. For development and testing, Basic Micro provides development boards which have computer and power connections, as well as a breadboard area for circuit design. Once your circuit is finalized, you can use a Basic Micro prototyping board or design your own board to accommodate the BasicATOM module. One-time projects can be left on the prototyping board permanently. Software The BasicATOM Language The BasicATOM language is a version of MBasic, with added functions to support the BasicATOM's hardware capabilities. How the BasicATOM Supports Software The BasicATOM includes the following software support facilities: * a microprocessor to run your program * a program loader to install programs developed using the Basic compiler * 14KBytes,32KBytes or 56KBytes (see Characteristics for specifications) bytes of flash program ROM, for storing programs and constants. Flash can be erased and rewritten many times. * 300bytes, 2Kbytes or 4Kbytes (see Characteristics for specifications) of RAM for calculations and variable storage (minus system overhead). * 256bytes or 4Kbytes EEprom on some modules. The runtime environment (sometimes known as a "Kernel", runtime library, or runtime module) is not permanently stored in the CPU. This gives greater flexibility so that commands and functionality can be added and modified without changing hardware. The runtime environment is automatically generated by the compiler, and can vary in size from very small to fairly large. As more functions are used in a program, the runtime environment will automatically expand to include support for these functions. The runtime environment is optimized and only includes support for functions actually used in your program. The support code for a function used in a program is only included once, even if the function is used many times. Hardware The BasicATOM is an integrated microcontroller based on a PICmicro(Standard) or Renesas(Pro) processor chip. ''Important: Users are strongly advised to obtain a copy of the PICmicro 16F876A,16F877A,16F886,16F887,H8/3694F or H8/3687F hardware manuals, depending on which version/revision module you are using, available at http://microchip.com or http://www.renesas.com which give important details for the chips used to build the BasicATOM modules.'' The BasicATOM modules add support circuitry (RS-232, voltage regulation, oscillator, etc.) and a program loader to the processor chip. For more specific information, refer to the data sheet supplied with each BasicATOM module (data sheets are also available on our web site, in the Download section, as PDF documents). The BasicATOM is programmed by means of a serial data stream at 115kb/s. This data format is supported by all modern PCs (since 1996 or before). The BasicATOM and BasicATOM development boards provide an RS-232 connector that can be connected by a standard cable to your PC’s serial port. BasicATOM Characteristics Chapter 3 - Getting Started This section explains in simple terms how to get started using your BasicATOM module. While some hardware basics are explained and a simple examples given, general hardware design for BasicATOM controlled devices is beyond the scope of this manual. What You Will Need Project development is normally done using hardware prototypes. Basic Micro provides Development Boards for this purpose. If you’re using your own development environment suitable power and RS-232 connections will be needed. You will need: * A BasicATOM module. * A BasicATOM development board (or your own suitable hardware development environment). * A suitable power source(5.5-12v on Vin or 5v regulated on Vdd). * An RS-232 connector and cable to connect to a PC serial port. * A USB cable (for programming using the Basic Atom Lab Board) * Appropriate BasicATOM software for Standard or Pro modules(Integrated Development Environment) * A PC running Windows 2000, NT4, XP or Vista. A CD drive is required to install the software included with the development kit; software may also be downloaded from our website. ''Note: We recommend a Pentium III or faster: operation may be quite slow with lesser computers, though they should work.'' All items except the PC are supplied with BasicATOM development kits. Follow These Steps Designing a project is as simple as following these steps: # Set up the BasicATOM software (IDE). # Build your circuit on a development board (these have "breadboards" to allow easy wiring and frequent changes). # Write the software to control your circuit and download it to the BasicATOM. # Debug and revise your hardware and software. What you do next depends on what you need. If you’re building: * a one-time project, and won’t need the development board for future projects, you can leave the circuit on the breadboard. Note that the long-term stability of breadboard projects may not be as good as those with soldered connections. * a one-time or limited production project, but want to re-use the breadboard for other projects, or want smaller size and the permanence of soldered connections, transfer your project to a BasicATOM Prototyping board. * a project for production, or just want to do your own board, design a suitable board incorporating your circuit. ''Note: For production lots use a development or prototyping board to program BasicATOM modules or interpreter chips, then transfer the programmed modules or chips to your production boards. You don’t need the circuit for programming on the production board unless you want to allow in-field reprogramming.'' Software Setup Software setup is easy and follows standard Windows practice. # With Windows running, insert the CD into the CD drive. (Current software is also available for download at our web site.) # If the installation program doesn’t automatically start, open an Explorer or My Computer window, navigate to the CD, and double click the "setup" icon or the file "setup.exe". # Installation from this point is automatic. Once done, there will be a BasicATOM icon on your desktop. # Double click the BasicATOM icon to open the Integrated Development Environment (IDE). # Go to Tools : System Setup or Properties(depending on IDE used) and choose the serial port to be used for connecting the development board (see Figure 1). Click Find BasicATOM if it is connected but you don’t know which port to choose. (The other tabs in the Pro IDE aren’t needed at this point.) Close the window. Figure 1 - Setting the serial port That’s it! You’re ready to start programming and working with your BasicATOM module as soon as it’s connected and ready. Hardware Setup For circuit and program development you will probably want to use a Universal Development Board which provides power, RS-232 programming connector, and a hardware breadboard area. Setup is easy (see Figure 2, Figure 3 and Figure 4): # Make sure you’re in a static free working environment. Microprocessors of all types are sensitive to static electricity and can be damaged if not properly handled. # Plug the module into the development board socket, making sure to align it at the end marked Pin 1 (see Figure 3). Be sure not to bend any of the pins. ''Important: If the pins seem too widely spaced to fit into the socket, hold the module by the ends, and gently "roll" the leads against a tabletop. Do this for each side until the pins slide easily into the socket.'' # Connect the provided RS-232 cable (9 pin connectors) to the 9 pin socket on the development board. # Plug the other end of the cable into an available serial port on your PC. (If the PC uses a 25 pin connector, use a 9 to 25 pin adapter, available at most computer stores. PCs without serial ports can be connected using a USB to RS-232 adapter.) # When you’re ready to begin programming and experimentation, plug the 9VDC power adapter into the socket on the development board. ''Important: Never make hardware changes in the prototype area or plug-in or un-plug the BasicATOM module with the power connected!'' If you’re using a BasicATOM module without a development board, you’ll need to provide your own RS-232 and power connections. The BasicATOM has a voltage regulator and an RS-232 level converter built-in. See the data sheet for connection details. Setup sequence for 24, 28 and 40 pin modules The diagram on the next page shows the setup sequence if you're using a BasicATOM module with the Universal Development Board. Figure 2 - Hardware Setup Sequence Make sure to orient the module correctly before plugging it in to the development or prototyping board. Look for the notch at one end of the socket, then align Pin 1 of the module with Pin 1 of the socket. Pin 1 on the module can be found by referring to the diagram below. ''Note: If the module has fewer pins than the socket, it must be plugged in at the Pin 1 end of the socket.'' Figure 3 - Orienting the Module Building Your Prototype or Project While it’s beyond the scope of this manual to discuss hardware design in detail, here are a few pointers to get you started. The best way to design your hardware prototype or project is to use a Basic Micro development board (see our web site and the list on page 5 for available models). Development boards include a breadboard area for easy experimentation and circuit development. Figure 5 shows a typical breadboard (Atom Universal Development board shown). Connections for microcontroller I/O, Vss and Vdd are provided. The board is marked to indicate voltages and pin numbers. Figure 5 - Typical Prototyping Area Component leads can be inserted directly into the holes in the breadboard. Jumpers can be made with #22 AWG or #24 AWG wire. Sockets in the breadboard are grouped together as shown below in Figure 6. This makes it easy to connect components together or to "fan out" voltages or I/O pins to multiple connections. Figure 6 - Breadboard internal connections The breadboard uses standard 0.10" spacing so small integrated circuits or other DIP (dual inline package) or SIP (single inline package) components can be inserted directly. Make sure that DIP components are inserted so as to "bridge" the central area, as shown in Figure 7. Figure 7 - IC orientation on Breadboard Once you’ve designed your experimental circuit or prototype, you’re ready to program the BasicATOM Pro and try it out! Running the IDE Software This section gives a brief overview of the IDE to help you get started. More complete information, including how to use the debugger, is included in the online help file. Double click the Atom icon (on your desktop or in your Start menu), then click on File | New to open the CreateFile dialog. It defaults to bas type files but can be set for C/C++,Asm or Txt files as well from the dropdown list. After choosing the directory to create the file in, type in the filename you want to use. We chose to use a Basic file with "test.bas" for our filename. Your screen should now look like this: Figure 8 - IDE screen The window is divided into three main areas: The File Explorer Window (at top left) displays directories and files. Figure 9 - IDE Workspace You can get more window room for your program by turning off the File Explorer Window: either click the X at its top right corner, or from the View menu choose Toolbars, and uncheck the "Workspace" toolbar. The Build area (at bottom) shows error messages and compile time messages. Turn it off by clicking the X in its top right corner, or via the View | Toolbars menu ("Results" toolbar). Once you’re done writing your program, you should turn it back on again before compiling (so you can see messages). You’ll notice that the programming area isn’t maximized; just click the maximize button (on the "test.bas" bar) and your window will look like this: Figure 10 - IDE Screen with program space maximized Once you’ve typed in your program, you can test it for errors by clicking the Compile button. This will compile your program, but will not write the output to the BasicATOM Pro. Alternately, you can simply click the Program button, which will compile your program and send it to the BasicATOM Pro. The program will start running on the BasicATOM Pro immediately. Now let’s use a concrete example to help you figure all this out. Chapter 4 - Let’s Try it Out To help you get started on your project, we’ll start by setting up a simple circuit or two, writing programs to operate them, and testing to see that they work. Once you’ve been through the procedure, you’ll be all set to work on your own. Here’s what you’ll learn: # How to set up a simple circuit on a breadboard. # How to write a simple program to control the circuit. # How to install and run the program on the Atom Pro. # A few troubleshooting pointers. Once you’re done, we’ll make a slightly more complex circuit, with a few additional programming details, and after that you’re on your own. Your First ATOM Pro Project We’ll start with a simple project to flash a LED (light emitting diode). Here’s everything you’ll need: * A BasicATOM Pro. * A development board (we used the Atom Universal Development Board). * Power supply, cables, etc. supplied with the development board. * A PC with the BasicATOM Pro software installed. * A red LED with wire leads. * A 2.7 kΩ ¼ W resistor. (Other values in the range of 1 kΩ to 4.7 kΩ should work). * Some #22 AWG or #24 AWG solid insulated wire for jumpers. The circuit is very simple, just a resistor and the LED in series. Note that the anode end of the LED (connected to the resistor) may be marked by a longer lead or a flat side on circular LEDs. ''Note: Before going any further, make sure you’ve followed all the steps for Getting Started, beginning on page 7.'' You can wire this circuit on the breadboard area of the development board (see Figure 11). Figure 11 - Blinker circuit on breadboard Don’t worry too much about the orientation of the LED at this point; it if doesn’t blink after programming, try reversing it. Writing the Program By this time you should have the BasicATOM Pro IDE software installed and running on your computer. Next: 1. Plug in the power for the development board. 2. Using the IDE, click on File | New, and choose a Basic file. 3. Type in the following short program: Main high P0 pause 200 low P0 pause 200 goto main End Use the TAB key to indent lines (this is only needed to make the program easier to read; the compiler doesn’t care). 4. Click on the Program button on the IDE. The program should compile, and be downloaded to the BasicATOM Pro without errors. 5. Watch the LED: it should be flashing 2.5 times per second. Troubleshooting If the IDE shows errors, recheck that you’ve typed the program correctly; it’s not likely that there would be some obscure, hard to find error in such a simple program. If the LED doesn’t flash, it is probably plugged in "backwards". Unplug it and plug it in with the leads reversed. Still doesn’t flash? Check the voltage on both resistor leads: it should alternate between 5V and 0V on the end connected to P0, and between about 1.2V and 0V on the end connected to the LED. Program Notes Let’s take another look at that program and add some comments. Main ;Start of program high P0 ;Set P0 to "high" (5V) pause 200 ;Wait for 200 ms low P0 ;Set P0 to "low" (0V) pause 200 ;Wait another 200 ms goto main ;Do it again, forever End "Main" is a label; in this case it’s at the beginning of the program. We need it so that the "goto" can find its way back to restart the program, making operation continuous. "End" is not a label, it’s an instruction to the compiler, telling it that the program code is now finished. '''''Permanency Once you’ve programmed the BasicATOM Pro, the program remains permanently in memory until you overwrite it with another program. Try this: # Unplug the power from the development board. # Disconnect the RS-232 programming cable. # Reconnect the power to the development board. Programs in memory start automatically as soon as the power is applied and your LED is flashing again; just as it was before. Note that you can restart a "stuck" program by pressing the RESET button on the development board. Making a Traffic Light As a second project we’ll wire up a miniature "traffic light". The idea is to show some slightly more complex programming techniques, as well as more sophisticated use of the breadboard. The traffic light uses three LEDs, one red, one yellow and one green. We’ll set it up to follow this sequence: * A 10 second red light, followed by * A 10 second green light, followed by * A flashing green "priority" light, and finally * A 3 second yellow (amber) light The cycle repeats forever until you turn off the power. You’ll need the following parts in addition to the ones from our first project: * A yellow LED * A green LED * A 2.7 kΩ ¼ watt resistor * A 1.5 kΩ ¼ watt resistor We’re using a lower value resistor to make up for the yellow LED’s reduced efficiency, which would otherwise make it too dim. The circuit is really just the first project repeated 3 times: Wire it up on the breadboard as shown in Figure 12. Figure 12 - Traffic light If you’re using the Atom Pro development board, the P0, P1 and P2 connections are available at the edge of the breadboard area. The Traffic Light Program Open a new basic file in the IDE and type in the following program: main counter var word ;must define variables red con P0 ;red LED on P0 yellow con P1 ;yellow LED on P1 green con P2 ;green LED on P2 low red ;turn all the LEDs off low yellow low green loop ;main program loop high red ;turn on red LED pause 10000 ;wait 10 seconds low red ;turn off red LED high green ;turn on green LED pause 10000 ;wait 10 seconds low green ;turn off green LED for counter=1 to 10 ;This loop flashes the high green ;green LED 10 times pause 300 low green pause 300 next high yellow ;turn on yellow LED pause 3000 ;wait 3 seconds low yellow ;turn off yellow LED goto loop ;start over again end Once you’re done, make sure the BasicATOM Pro is connected to the computer, and click the Program button. Your program should compile and download without errors, and your LEDs should light in the sequence described above. Compile time errors are probably a result of typing mistakes; the printed program above is taken directly from a working model without retyping. The IDE window should look much like this once you’re done: Figure 13 - IDE Screen while compiling Traffic Light program Program Notes This program has a couple of additional features that are worth discussing. The section following Main defines variables and constants. Unlike many basics, all variables used in Atom Basic must be defined before they’re used. So a simple "for x = 1 to 10" won’t work unless you’ve defined "x" at the beginning of your program. Here we’ve defined the variable "counter" as a "word" variable (i.e. 16 bits) in the line: counter var word. We’ve also defined some constants. For convenience, instead of having to remember that P0 is red, P1 yellow, etc. we’ve defined the constants "red", "yellow", and "green" (e.g. red con P0). Definitions are followed by a label "loop". This provides a re-entry point that does not set the lights to OFF each time the program cycles. Understanding the Build Window The bottom pane in Figure 13 shows the results of compiling your program. In our example, scrolling the Build Window will show the following lines: Starting Compiler... Preparing Files... C:\MY DOCUMENTS\TRAFFIC.BAS Compiling... Tokenizing... Ram Memory Bytes Used(System): 4 Ram Memory Bytes Used(User): 2 Ram Memory Bytes Free(Stack): 2042 Program Memory Bytes Used(Tokens): 176 Program Memory Bytes Used(Library): 1756 Program Memory Bytes Used(Total): 1932 Program Memory Bytes Free: 29812 No Errors Detected Programming... Most of the lines are self-explanatory, a few notes will help to clarify others. "Tokenizing" is the process of converting input words into numbers (tokens) recognized by the compiler. The number of "tokens compiled" is the number of unique commands in your program. RAM Memory Bytes are used by the system, stack and User. In our example we defined the variable "counter" as a "word", i.e. two bytes, as shown above. Programming Multiple BasicATOM Pros Multiple BasicATOM Pro modules can be programmed in sequence from the same source program; just connect each one in turn to the computer and click the Program button. Note that the program will be recompiled for each BasicATOM PRO Programmed, the object code (i.e. the code that’s downloaded to the BasicATOM Pro module) is not retained by the IDE for re-use. Summary You’ve learned about the components that make up a BasicATOM Pro development system. You’ve learned to run the software, write a program, set up the hardware, and test a couple of simple projects. By now you should be feeling quite at home with the BasicATOM Pro. Now it’s time to plan your own applications and projects. The rest of this manual is devoted to Atom BASIC details, compiler directives, syntax, etc.